A.C.E. 3/ACE CD 3.iso/files/docs/candodoc.lha/CandoPart2.doc

Text File | 1994-11-27 | 105.1 KB | 3,072 lines

            part 2 of cando manual


SYSTEM VARIABLES

    System Variable can be used in expressions as variables. Some of
these variables return dynamic information that is updated by CanDo. Others
have static values for common uses:

    Boolean Values:

    «logical» = FALSE    - Boolean Value (FALSE).

    «logical» = TRUE    - Boolean Value (TRUE).

    «logical» = NO    - Boolean Value (FALSE).

    «logical» = YES    - Boolean Value (TRUE).

    «logical» = OFF    - Boolean Value (FALSE).

    «logical» = ON    - Boolean Value (TRUE).

    Informational:

    <integer> = AvailableChipMemory    - available bytes in chip memory.

    <integer> = AvailableFastMemory    - available bytes in fast memory.

    <integer> = AvailableMemory    - available bytes in memory.

    <integer> = LargestChunkOfMemory    - the largest continuous chunk of
                      available memory.

    "string" = DeckName    - the name of the current Application.

    "string" = CardName    - the name of the current Card.

    "string" = ObjectName    - the name of the current running Object.

    <integer> = MaxInteger    - returns  2.147.483.647.

    <integer> = MinInteger    - returns -2.147.483.647.

    «logical» = Supervised    - TRUE when running from CanDo.

    "string" = TheTime    - returns the current time - "HH MM SS".

    "string" = TheDate    - returns the current date - "YY MM DD".

    CanDo has a number of System variables that are closely related with
a group of Commands. These System variables are documented in the sections
with these Commands.

                                     6-17

                            Flow Control Commands

    The Flow Control commands allow you to change the order of execution
within a script. Usually, commands execute one at a time from top to bottom.
These Commands effect this flow of execution.

If... Endif

    The If Command allows you to execute a group of instructions when a
certain condition is TRUE (see Logical Expression).

If { logical expression }
    ...Commands...

Endif

    The commands between the If command and the Endif command are
performed only when the logical expression is true.

Example:
    If NumberOfHits > 10
        ShowBrush "Brushes:Explode.br"
        PlaySound "sounds:bang.snd"
    Endif


If... Else... Endif

    The Else Command can be used with an If to perform an alternate set
of commands when the logical expresson is false.

Example:
    If NumberOfHits > 10
        ShowBrush "Brushes:Explode.br"
        PlaySound "sounds:bang.snd"
        Let NumberOfHits = 0
    Else
        PlaySound "sounds:Doink.snd"
        Let NumberOfHits = NumberOfHits + 1
    Endif

    The commands between the If and the Else are performed when the value
of NumberOfHits is greater then 10. Otherwise, the Commands between the Else
and the Endif are performed.
    CanDo supports four looping combinations. These Commands allow you to
repeat a group of commands given specified conditions.

                                     6-18

While... EndLoop

    CanDo supports four looping combinations. The While Command allows
you to repeat a group of Commands while a condition is TRUE. The form for a
While Command is:

    While { logical expression }
        ...Commands...
    EndLoop

    The Commands between the While and EndLoop are performed while the
logical expression is TRUE. When the While instruction is encountered, the
logical expression is evaluated. If the condition is TRUE, the Commands
between the While and the EndLoop are performed. When the EndLoop Command is
encountered, execution is looped back to the While Command. This continues
until the logical expression is FALSE.
    When the logical is FALSE, all Commands between the While and EndLoop
are skipped, are execution continues on the instruction following the EndLoop.

Example:
    Let Xoffset = 20
    While Xoffset <= 300
        ShowBrush "Brushes:Arrow.br",Xoffset,40
        Let Xoffset = Xoffset + 20
    EndLoop


Loop... Until

    The typical format for the Until Looping Command is shown below.

    Loop
        ...Commands...
    Until { logical expression }

    The Until works in a similar manner as the While Loop. The commands
between the Loop and Until are performed until the logical expression is TRUE.
The Until Loop is used when you want the Commands in the Loop to be performed
once before evaluatine the logical expression.

Example:
    Let Xoffset = 20
    Loop
        ShowBrush "Brushes:Arrow.br",Xoffset,40
        Let Xoffset = Xoffset + 20
    Until Xoffset > 300

                                     6-19

While... Until

    This Looping combination, while unusual, is valid. The format for the
While and Until Looping Commands is shown below.

    While { logical expression }
        ...Commands...
    Until { logical expression }

    The Commands between the While and Until are performed as long as the
While's logical expression is TRUE and the Until's logical expression is
FALSE.


Loop... EndLoop

    The form of Loop and EndLoop Commands is shown belov.

    Loop
        ...Commands...
    EndLoop

    This is a simple looping system. All commands within the looped area
are repeated until an 'ExitLoop' command is executed. You should be very
careful insuring there is a way for the ExitLoop to be performed. It is
usually within an If... Endif placed in the Loop commands.


ExitLoop

    Exits the Highest Loop Level. This command is usually within an If...
Endif in the Loop commands. It can be used to exit any of the Loop
combinations. If you have nested Loops ( Loops within Loops ) it exits the
hightest Loop level.
    Note: Your Scripts will be more readable if you use the While and
Until conditional Looping instead of ExitLoop.

                                     6-20

Do "Routine Name" {, Argument1... , Argument10 }

    The Do Command performs the routine created using the Routine Object.
The "routine name" must match the Name used in the ROUTINE EDITOR REQUESTER.
This is very similar to the Gosub used in other languages. The Commands within
the routine will be performed, and execution will continue with the Command
following the Do.
    You can use the ROUTINE EDITOR TOOL for finding the available routine
names.

    Example:
        If value = 5
            Do "ShowExplosions"
            Do "SoundEffects"
        Endif

    Optionally, you can pass a routine up to 10 arguments. An argument is
simply a value that the calling script gives the routine.

    Do "Draw Box",2,10,20

    This example calls the Routine "Draw Box" and passes it three
arguments: 2,10, and 20. While this example uses constants, each argument can
be an expression.
    The routine "Draw Box" can use the arguments to perform its task. It
does this using the System Variables Arg1 through Arg 10.

    SetPen Arg1
    DrawRectangle Arg2,Arg3,50,25

    If the routine "Draw Box" contained this script, it could use three
arguments to draw a box. Arg1 is used with the SetPen Command to set PanA. The
previous example passed a value of 2 for the fist argument. This would result
in setting PenA to color 2. The DrawRectangle Commands draws a box with a
width of 50 and a height of 25. Its origin would be determined by the second
and third arguments. Using the previous example, this would draw the box at
10,20.

                                     6-21

ExitScript

    A Script usually exits after performing the last Command. An
ExitScript exits as though the last Command was performed. If the ExitScript
is performed from a Routine, execution will continue in the calling Script.


StopScript

    The StopScript command is similar to an ExitScript. However, if it is
performed from a Routine, execution will not continue in the calling Script.
It does not run your application, it simply terminates the execution of the
current Script, and any scripts that may have called it using a Do Command.


Quit

    This Command allows the user to exit the presently running Deck.
While you are developing you application, CanDo will not allow you to exit
using a Quit Command. However, when you run it as a separate application, it
is important to provide a way to Quit.

                                     6-22

                            Card Movement Commands

    These Commands change Cards in the Deck. They correspond to the Card
Movement Buttons on the MAIN CONTROL PANEL.

NextCard

    NextCard goes to the next Card in the Deck. If you are currently on
the last Card in the Deck, It will go to the first Deck.

PreviousCard

    PreviousCard goes to the provious Card in the Deck. If you are on the
first Card, it will go to the last Card.

FirstCard

    FirstCard goes to the first Card in the Deck.

LastCard

    LastCard goes to the last Card in the Deck.

GotoCard

    GotoCard "cardname"

    You can use a Card's Name to move directly to a specific Card with
the GotoCard Command. The name must be spelled exactly as it was spelled in
the CARD EDITOR REQUESTER. The "cardname" is a string parameter.

    Example:
        GotoCard "Card #2"

                                     6-23

                               Graphic Commands

    The Graphic Cammands change the images in your Card's Window. This
can be done by showing pictures and brushes, by drawing images or displaying
Text. In addition, there are variety of commands that control how other
drawing commands are performed.

Picture and Brush Commands

    CanDo's Picture and Brush Commands allow you to show images created
with any Paint Program. These commands include "Clipping" allowing you to copy
images from your window. These clipping images can then be displayed or saved
to a file.


LoadPicture "filename" {, "name" {, loadflags } }

    Before an image can be displayed, it must be loaded into memory. This
can be done automatically with the ShowPicture Command. However, there will be
a delay as the image is loaded. This may be OK most of the time. However, it
can be avoided by pre-loading the image using the LoadPicture Command. The
LoadFlags are described in the LoadFlags Appendix.

    "Filename"

    The "FileName" is the file specification for the image being loaded.
It must be a valid ILBM file type created by most Amiga Paint programs.

    "Name"

    The optional "Name" allows you to specify the name used by a
ShowPicture Command. When the "Name" is not specified, the ShowPicture Command
must use the exact same string used in the "filename".

    Example:
        LoadPicture "images:backgrouned.pic","background"
        ShowPicture "background"


LoadBrush "filename" {, "name" {, loadflags } }

    The LoadBrush Command works simiarly to the LoadPicture Command,
except is pre-loads a brush file created by a paint program. It can then be
shown using the ShowBrush Command. The parameter are identical to
LoadPicture's parameters.

    Example:
        LoadBrush "brushes:theleftarrow.br","LeftArrow"
        ShowBrush "LeftArrow",10,190

                                     6-24

ShowPicture "Picture Name"

    The ShowPicture Command is used to change the picture being
displayed. CanDo automatically adjusts the screen resolution and color
palette. Furthermore, Visible Objects are re-displayed on the new picture.
    You should be careful when using pictures of different dimensions.
Objects, such as Buttons, are displayed at specified Horizontal and Vertical
locations. For Example: If the original window had a width of 640 and a
picture having a width of 320. The safest approach is to use different cards
with pictures having different dimensions.

"Picture Name"

    The "Picture Name" indicates the file to be displayed. The name can
be a file specification. If so, CanDo will automatically load it if is is not
already in memory. It can also be a "Name" specified in a LoadPicture Command.

    Examples:
        ShowPicture "images:BigBird.pic"

        LoadPicture "images:Background.pic","TheBackground"
        ShowPicture "TheBackground"


ShowBrush "Brush Name" , < X > , < Y > {, BRUSHPALETTE }

    This command shows a DPaint style brush at a specified location on
the current window. Optionally, you can use the color palette saved with the
brush. You will have more predictable result if the Brush uses the same
resolution as the current picture.
    BRUSHPALETTE indicates to use the palette saved with the brush.

    Examples:
        ShowBrush "brushes:Bat.br",500,25

        LoadBrush "brushes:helloworld.br","theimage"
        ShowBrush "theimage",50,50,BRUSHPALETTE

                                     6-25

SavePicture "Picture Name" {, "Filename" }

    The SavePicture Command lets you save a picture. The picture can be
one that was loaded or created using the ClipPicture Command. It can either
save it in the original file or create a new one. The "Picture Name" indicates
the picture to save. The optional "filename" allows you to explicitly indicate
the filename to use. If the "filename" is not speicfied, CanDo will either
save the file using the original filename, or use the "Picture Name" as the
file specification if it was created using the ClipPicture Command.


SaveBrush "Brush Name" {, "Filename" }

    The SaveBrush Command allows you to save a brush. This command works
similarly to the SavePicture Command, except the image is saved in the Brush
format. The parameters work the same way as the SavePicture Command
parameters.


ShowPalette "Name"

    This command changes the palette to the one saved with a picture or
brush. The "Name" is either the file specification or the name used with the
LoadPicture or LoadBrush Commands. If the image is not currently in memory,
the ShowPalette Commands will use the "Name" as a file specification from
which to read the palette from a file.

                                     6-27

Transparent «logical expression»

    When a brush is saved, the background color is called Transparent.
This means instead of seeing the color, you can "see through" it. CanDo allows
you to turn this ON or OFF before showing a brush.
    The «logical expression» indicates whether to turn transparency on or
off. When the expression is TRUE (or ON) you will be able to see through the
transparent color. Otherwise, the background color will be shown. Most of the
time you will to use the constats ON or OFF.

    Examples:
        Transparent ON
        ShowBrush "brushes:Arrow.br",20,30

        Transparent OFF
        ShowBrush "brushes:Dog.br",120,40


ClipPicture "Picture Name" {, CHIP }

    ClipPicture allows you to make a copy of the current card's window.
The "Picture Name" names the image so you can use it later in a ShowPicture or
SavePicture Command. If the "Name" is currently being used, it will be
replaced with the clipped picture. The CHIP keyword indicates to save the
image in the Amiga's Chip memory.


ClipBrush < X > , < Y > , < Width > , < Height > , "Brush Name" { ,CHIP }

    ClipBrush lets you grab a portion of the current card's window and
use it as a brush. The <X> and <Y> indicates the Origin, the location of the
upper left corner, of the area to be clipped. The <Width> and <Height>
indicates the number of pixels horizontally and vertically, from the Origin,
to clip. The "Brush Name" gives it a name so you can use it in a ShowBrush or
SaveBrush Command. If the "Brush Name" currently is being used, it will be
replaced with the clipped brush. The CHIP keyword indicates to save the brush
in the Amiga's Chip memory.

SetClipTransparentColor < color >

    The SetClipTransparentColor Command sets the background color used in
a clipped brush. This color is transparent in a ShowBrush Command when
Transparent is ON.

                                     6-26

Draw Commands

    CanDo uses the Amiga Operation System supplied graphics routines.
They do not make color corrections for HAM. This means you may see some
"jaggies" when drawing in HAM mode. This can be minimized or eliminated by
only drawing on portions of the picture that use the 16 primary colors.
(AmigaWorld's March 1989 issue has a good description of HAM).


AreaCircle < X > , < Y > , < R >

    Draws a filled circle with a center of <X>,<Y> and a radius of <R>.
The circle is filled with the color i PenA. The aspect ratio si not corrected
for High-Resolution Screens.

    Example:
        AreaCircle 50,50,25


AreaEllipse < X > , < Y > , < XR > , < YR >

    Draw a filled ellipse with a center at <X>,<Y>. The horizontal radius
of the ellipse is <XR> and the vertical radius is <YR>. The ellipse is filled
with the color in PenA.

    Example:
        AreaEllipse 50,05,25,50


AreaRectangle < X > , < Y > , < W > , < H >

    Draws a filled rectangle with an upper left coordinate at <X>,<Y>.
The width of the rectangle is <W> and the height is <H>. The rectangle is
filled with the color in PenA.

    Examples:
        AreaRectangle 50,50,100,100
        AreaRectangle 52,52,96,96


FloodFill < X > , < Y >

    The FloodFill Command fills a solid shape starting at <X>,<Y>. If
will fill using the color in PenA. The shape is determined by the color at
location <X>,<Y>.

    Example:
        SetPen 7
        FlooFill 50,50

                                     6-28

FillToBorder < X > , < Y > , < BorderColor >

    The FillToBorder fills a shape starting at <X>,<Y> and is outined in
the color specified be the <BorderColor>. Like FloodFill, it will fill using
the color in PenA.

    Example:
        SetPen 3
        DrawRectangle 10,10,100,100
        SetPen 1
        FillToBorder 20,20,3


DrawCircle < X > , < Y > , < R >

    Draw a circle with a center of <X>,<Y> and a radius of <R>. The
aspect ratio is not corrected for High-Resolution Screens.


DrawEllipse < X > , < Y > , < XR > , < YR >

    Draws an ellipse with a center of <X>,<Y>. The horizontal radius of
the ellipse is <XR> and it's vertical radius if <YR>.

    Example:
        DrawEllipse 50,50,25,50


DrawLine < X1 > , < Y1 > , < X2 > , < Y2 >

    This command will draw a line from <X1>,<Y1> to <X2>,<Y2>. The
current pen position will be set to <X2>,<Y2>.

    Examples:
        DrawLine 50,50,100,50

        DrawLine 50,52,100,52


DrawPixel < X > , < Y >

    Draws a single pixel at a certain location. This command uses the
present drawmode and will set the current pen position to that of the pixel
drawn.

    Parameters:

    < X >    The Number pixels from the window right hand border.

    < Y >    The Number pixels from the window top border.

                                     6-29

DrawRectangle < X > , < Y > , < W > , < H >

    Draw arectangle with an upper left coordinate of <X>,<Y>. The width
of the rectangle is <W> and the height is <H>. No aspect ratio computations
are computed. The current pen positoin is set to the <X>,<Y> of the rectangle.

    Examples:
        DrawRectangle 50,50,100,100

        DrawRectangle 52,52,96,96


DrawTo < X > , < Y >

    This command is similar to the line Command. However, it uses the
current pen position for the starting point for the line. It draws a line from
the current pen position to the specified window coordinate. After drawing the
line, the pen positon will be set to the specified window coordinates.

    Example:
        Line 50,05,100,50
        DrawTo 100,100


MovePen < X > , < Y >

    Moves the pen to the specified window coordinate. This command does
not draw any points in window.

    Example:
        MovePen 50,50


RayTo < X > , < Y >

    This is similar to the DrawTo Command. With this command a line is
drawn from the current pen position to the specified window coordinate.
However, the current pen position is not modified.

    Example:
        Let XPos=60
        MovePen 160,100
        While XPos <=260
            RayTo XPos,10
            Let XPos=XPos+40
        EndLoop

                                     6-30

ClearWindow { <color> }

    The ClearWindow Command clears the window to its inital state. This
means it will redisplay the image if it is a Picture Window. If it is not a
Picture Window, it will clear the window to the color specified in the Window
Color Requester or to the optional <color>. In either case, all visible
objects will be redisplayed.

    Examples:
        ClearWindow

        ClearWindow 5


Graphics Control

    The Graphics Control Commands change various values that effect the
other Graphic Commands.


GetRGB < col.reg. > , < red var. > , < green var. > , < blue var. >

    Gets the RGB values from a specified color register. The RGB values
range from 0 to 255. Remember that different view mode use the color registers
very differently.

    < col.reg. >    The color register to read.
    < red var. >    Variable for the red part of the register.
    < green var. >    Variable for the green part of the register.
    < blue var. >    Variable for the blue part of the register.

    Example:
        GetRGB 1,RedValue,GreenValue,BlueValue


SetAreaDrawMode NORMAL or OUTLINE

    The SetAreaDrawMode Command only effects the Area Commands:
AreaCircle, AreaEllips, and AreaRectangle. The default mode is NORMAL. When it
is NORMAL, the area is drawn in a solid color using PenA. When it is OUTLINE,
the Area is drawn using PenA outlined with the color in PenO. When this draw
mode is set, all subsiquent Area Commands will use the specified mode.


SetDrawMode { Normal } { Jam1 } { Jam2 } { Complement } { InverseVideo }

    This command allows the user to specify the drawing style they wish
to use. The keywords can be used with one another (i.e. SetDrawMode Normal
InverseVideo).

{ Normal }    Draw with the primary pen.
{ Jam 1 }    Same as the Normal switch.
{ Jam 2 }    Draw with both primary and secondary pen.
{ Complement }    Performs a logical XOR on the pixel's own color info.
{ InverseVideo }    Performs a logical NOT on the other draw modes.

                                     6-31

SetPen < PenA > {, < PenB > {, < PenO > } }

    Set the primary, secondary and outline pen's color register. This
command allows the user to specify which color to draw with. The PenB and PenO
are optional

    < PenA >    The color register for the primary drawing pen.
    < PenB >    The color register for the secondary drawing pen.
    < PenO >    The color register for the area outline pen.

    Example:
        SetPen 1
        DrawPixel 10,14


SetRGB < col.reg. > , < red > , < green > , < blue >

    Set the RGB values for the specified color register. The RGB values
range from 0 to 255. Remember that different view modes use the color
registers very defferently.

    < col.reg. >    The color register to read.
    < red >        Variable for the red part of the register.
    < green >    Variable for the green part of the register.
    < blue >     Variable for the blue part of the register.

    Example:
        SetRGB 3,RedValue,GreenValue,BlueValue


CycleColors < From-Color >, < To-Color > {, FORWARD or BACKWARD }

    The CycleColors Command cycles the current color palette. The
< From-Color > < To-Color > indicates the range. It does not make any
difference if the < From-Color > is less than the < To-Color >.
    The CycleColors Command rotates the colors once from the lower to the
highter. The optional keywords FORWARD and BACKWARD specify the direction of
the rotation. If neither is specified, it defaults to FORWARD. FORWARD
indicates lower values are torated upward. BACKWARD indicates the higher
values are rotated downward.
    The CycleColors Command can be placed in a reoccurring Timer Object
to provide continuous cycling.


    Example:
        CycleColors 5,10,FORWARD

    Reg. 0 1 2 3 4 5 -> 6 -> 7 -> 8 -> 9 -> 10 11 12 13 14 15 16
              ^                 v
              ^                 v
               <- <- <- <- <- <- <- <- <-

                                     6-32

Print Commands

    The Print Commands allow you to print text messages to the window.
You can use various fonts, sizes, colors, and enhanced print styles.


PrintText < X > , < Y > , "string"

    Prints the "string" using the current pen colors, print style, and
font. The x,y coordinate specifies the upper left corner of the text string.

    Example:
        PrintText 50,50,"Hello World"


SetPrintStyle StandardFlags { ExtendedFlags } {, < ExtPen1 > {, ExtPen2 > } }

    The SetPrintStyle Command specifies the style of print for subsequent
PrintText Commands. The StandardFlags are PLAIN, ITALIC, BOLD, and UNDERLINED.
You can specify one of more of these. Optional, you can specify one of the
ExtendedFlags: SHADOW, OUTLINE, GHOSTED, or EMBOSSED. Make sure you do not
seperate any of the flags with commas.
    The Extended Pens, < ExtPen1 > and < ExtPen2 >, are used with the
Extended styles. The PrintText command uses the color in PenA as the primary
color for drawing the text. When using an Extended style, the < ExtPen1 > is
used as a secondary color. The EMBOSSED style uses the additional color
< ExtPen2 >.

    Example:
        SetPen 1
        SetPrintStyle BOLD ITALIC
        PrintText "This uses a single color. It is BOLD and
              Italic.",20,20

        SetPen 0
        SetPrintStyle GHOSTED,5
        PrintText "The Primary Color is 0 GHOSTED in 5.",20,80

        SetPen 3
        SetPrintStyle BOLD EMBOSSED,1,2
        PrintText "The Center is Pen 3, with Color 1 and 2 on each
              side.",20,120


SetPrintFont "FontName" , < PointSize >

    Set the print font for the PrintText Command. If the operation system
connot find the point size you are looking for, it will give you the next
smallest size available. If the operation system cannot find the font you are
looking for, it will give you the font Topaz 80.

    Example:
        SetPrintFont "Topaz",9
        PrintText "Hello World",50,50

                                     6-33

GetTextDimensions "Text" , Width-Variable , Height-Variable

    This command sets the contents of two variables to the width and
height of the indicated "Text" string. It evaluates the "Text" using the
current font, point size, and print style. The Width-Variable and
Height-Variable must be valid variable names. The variables will be set to the
corresponding values.

    Example:
        GetTextDimensions "Hello" , Hello Width , Hello Height


Functions

    This Function can be used in expressions to return informaton
relating to Graphics Commands.


ColorOfPixel

    <integer> = ColorOfPixel ( <X>,<Y> ) -This is the Color of the Pixel
                      at the specified x,y location.


System Variables

    <integer> = PenA    -This is the Color Register for PenA.

    <integer> = PenB    -This is the Color Register for PenB.

    <integer> = PenO    -This is the Color Register for PenO.

    <integer> = ClipTransparentColor    - This function returns the
                      background color used when
                      clipping brushes.

    «logical» = TransparentStatus    - This function returns TRUE if
                      Transparent is enabled, and
                      FALSE if not.

                                     6-34

                          Screen and Window Commands

    The WINDOW OBJECT EDITOR allows you to define the Window when it
opens. The Window will open on either the Workbench, or a Custom Screen. If
you are not familiar with the way the Amiga works, the differences between a
Window and a Screen can be a little confusing. The Screen is the full-width
area of the display which defines the display mode, resolution, and color
palette. A Window is displayed on a Screen and can be its full size or
smaller.
    These Commands allow you to change the position and attributes of
both the Screen and Window.


MoveScreen < Delta - X > , < Delta - Y >

    The MoveScreen Command moves the screen a specified number of pixels
right or left, < Delta - X >, or up or down < Delta - Y >. Note that under
Amiga operation systems 1.3 and before, it is not possible to move a screen
borizontally. The delta integers make it easy to move the screen specific
distances without reference to its current position.

    Examples:
        MoveScreen 0,-10
            This would move the screen up 10 pixels.

        MoveScreen 0,10-ScreenY
            This example would move the screen to be 10 pixels
from the top. Because ScreenY indicates the current position. 10-ScreenY will
always positon it 10 pixels from the top.


ScreenTo FRONT or BACK

    The ScreenTo Command moves the screen either to the back of the
displayes screens or to the front of the displayed screens.

    Examples:
        ScreenTo BACK

        ScreenTo FRONT


ScreenTitleBar «logical expression»

    This command makes the screen (if it is your own, custom screen, and
not Workbench's screen) have a visible title bar. By using this command and
eliminating your window's title, and border, and all of your window's standard
objects (dragbar, closebutton, e.t.c.), you can use the screen's dragbar to
move the screen up and down with the mouse.


SetScreenTitle "Text"

    This sets the title of the screen to be the indicated text when your
window is the active window. If you have created a Workbench window, when your
window is inactive, the screen title bar will reflect some other name
(probably Workbench), and when your window is active the screen will show the
title set with this command.

                                     6-35

MoveWindow < Delta - X > , < Delta - Y >

    The MoveWindow Command moves the window a specified number of pixels
right or left, < Delta - X >, or up or down < Delta - Y >. The delta integers
make it easy to move the window specific distances without refeence to its
current position.


WindowTo FRONT or BACK

    The WindowTo Command moves the window either to the back of the
displayed windows or to the front of the displayed window. Because a Custom
Screen has only one Window, this command is only useful on a Workbench Window.
If the window was created in Backdrop mode (see Window Options), it cannot be
moved in front ot other windows.


SetWindowTitle "Text"

    The WindowTo Command sets the title of your window to the indicated
text. If you have previously removed all of the standard window objects,
border, and title, this will only add a bar to the top of your window in which
the title will be displayed. The Initial Window Title is set on the WINDOW
EDITOR REQUESTER.

SetWindowLimits < MinX > , < MinY > , < MaxX > , < MaxY >

    The SetWindowLimits Command controls the minimum and maximum size of
your window. With these limitations in place, your window cannot be resized by
the user to any dimensions outside of these ranges. It is often convenient to
use this command in the AfterStartUp Script of your card. In this way,
immediately after Window Object has been opened, you can set the limitations
on its sizw before the user has had a chance to resize you window.

                                     6-36

Current Screen and Window Information

    <integer> = MouseX    - Horizontal position of the mouse.

    <integer> = MouseY    - Vertical position of the mouse.

    <integer> = WindowColors    - Number of Colors.

    <integer> = WindowHeight    - Height of the Window.

    <integer> = WindowWidth    - Width of the Window.

    "string"  = WindowTitle    - Text in Window Title Bar.

    <integer> = WindowX    - Horizontal offset of the window.

    <integer> = WindowY    - Vertical offset of the window.

    <integer> = ScreenColors    - Number of Colors (same as WindowColors)

    <integer> = ScreenWidth    - Width of the screen.

    <integer> = ScreenHeight    - Height of the screen.

    <integer> = ScreenX    - Horizontal offset of the screen.

    <integer> = ScreenY    - Vertical offset of the screen.

    «logical» = Interlace    - TRUE when the screen is Interlace.

    «logical» = Hires        - TRUE when the screen is High-Resolution.

    «logical» = NTSC        - TRUE when NTSC Amiga; FALSE for PAL.

                                     6-37

                           Brush Animation Commands

    The Brush Animation Commands allow you to show, move, and control
DPaint III BrushAnims.
    You simply load the animation into a buffer using the LoadBrushAnim
Command. The ShowBrushAnim Command begins the animation on the screen. You can
specify a velocity for movement with the MoveBrushAnim Command, along with an
acceleration rate. Or you can use the MoveBrushAnimTo Command, which moves the
brush animation from it's current location to a distination with a specified
velocity and duration.

Features    * Use of DPaint III brush animations complete with the Forward,
      Reverse, PingPong, and Duration parameters.
    * Showing of multiple animations at the same time.
    * Movement of animations in your window with full clipping.
    * Real-time decompression in which each frame is decompressed into
      chip memory as needed, or
    * One-time decompression in which all frames are decompressed into
      chip memory. This uses more memory but provides faster animations.
    * Restoration of the background when the BrushAnims move.
    * Support for Transparent brush animations.
    * Sequenced animation that shows each frame in an animation before
      moving.


LoadBrushAnim "filename" {, "BrushAnim Name" {, loadflags } }

    The LoadBrushAnim Command reloads a DPaint III style brush animation.
The "filename" contains the file specification for the animation to be loaded.
The optional "BrushAnim Name" allows you to refer to the brush animation by a
name other than the "filename".


ShowBrushAnim "BrushAnim Name" , < X > , < Y >

    Adds the indicated brush animation to the window. The "BrushAnim
Name" indicates the DPaint III style brush animation to show. The name can be
a file specification or a name created using the LoadBrushAnim Command. If the
file is not already in memory, it will be loaded. The <X>,<Y> indicate the
initial location of the brush animation, before you can move it using either
the MoveBrushAnimTo or MoveBrushAnim Commands. Ind addition, a BrushAnim must
be shown to allow Animation Object's Scripts to be performed.


MoveBrushAnimTo "BrushAnim Name" , < X > , < Y > {, ticks }

    Moves the brush animation to the specified <X>,<Y> coordinates. If
<ticks> are not provided, the BrushAnim will move instantly. Otherwise,
movement will occur over the time specified iin <ticks>. If you have an
Animation Object watching this BrushAnim that has an OnDestination script
defined, it will be performed when the BrushAnim arrives at the specified
location.

                                     6-38

MoveBrushAnim "BrushAnim Name" , <Xvel>,<Yvel>,{ <Xacc>,<Yac > { <ticks> } }

    The MoveBrushAnim Command moves a currently displayed brush animation
"BrushAnim Name" in a direction and acceleration indicated bu the
<Xvel>,<Yvel>,<Xacc> and <Yacc> values.
    The <Xvel>,<Yvel> are the velocity values are added to the x,y
Movement (default) then the velocity values are added after each frame. If the
brush animation has Sequenced Movement, then the velocity values are added
after each animation sequence.
    The optional <Xacc>,<Yacc> are the acceleration values that are added
to the valocity values after each time they are added to the X,Y values. This
will cause the movement of the brush to accelerate. If they are not specified,
they default to 0. This causes the animation to move at a constant velocity.
    The optinal <ticks> value indicates the number of frams to move in
the specified direction. After it has moved for the specified number of
frames, it will stop. If you have an Animation Object watching this BrushAnim
that has an OnDestination script defined, it will be performed when the
BrushAnim arrives at the specified location.
    If the <ticks> is not specified, the animation will move continuously
in the indicated direction.


GetBrushAnimCoordinates "BrushAnim Name" , Xvariable , Yvariable

    Returns the x,y coordiantes of the brush animation in the indicated
variables.

    Example:
        GetBrushAnimCoordiantes "Helicopter",HeliX,HeliY

    This instruction will put the x location into the variable HeliX and
the y location into the variable HeliY.


RemoveBrushAnim "BrushAnim Name"

    The RemoveBrushAnim Command stops animating the specified "BrushAnim
Name". However, it does not erase it from the window and does not remove the
BrushAnim from memory. The BrushAnim can be removed from memory with Flush
Command.

                                     6-39

SetBrushAnimFlags "BrushAnim Name" , < brushanimflags > [, { ticks } ]

    This Command is used to specify some options for the specified
"BrushAnim Name". If the brush animation is not currently in memory, it will
be loaded.
    The brushanimflags are keywords that indicate specific options. Make
sure that you do not separate the keywords with commas.

    COMPRESSEDMODE or DECOMPRESSEDMODE
    indicates how the animation is kept in memory.
    COMPRESSEDMODE is the default mode; it takes less memory. However, it
    takes move time to animate because each frame must be created before
    it can be displayed.

    RESTOREBACKGROUND or LEAVEIMAGE
    indicates whether CanDo should save and restore the background each
    time the animation is shown. When RESTOREBACKGROUND option is used,
    you can move the animation without leaving a trail. However, it can
    substantially slow down the animation. LEAVEIMAGE is the default
    mode.

    USEMASK or NOMASK
    is the same thing as transparent mode for normal brushes. The
    background color saved with the Brush Animation is transparent when
    is it displayed. The USEMASK option increases the time required to
    display each animation frame, especially in COMPRESSEDMODE.

    SEQUENCEDMOTION or LINEARMOTION
    specifies how the animation is moved. SEQUENCEDMOTION shows each
    frame of the animation before moving it. LINEARMOTION moves the
    animation on each frame. SEQUENCEDMOTION only effects the
    MoveBrushAnim Command and not the MoveBrushAnimTo Command.

    FORWARD, BACKWARD and PINGPONG
    specify the order in which the animation's frames are shown. FORWARD
    plays the animation from first frame to last. BACKWARD plays the
    animation from last frame to first. PINGPONG switches between forward
    and backward motion each time the first or last frame of the animation
    is displayed.

                                     6-40

    NONE
    changes no flags. It simply allows you to specify the <ticks> without
    changing any flags.

    <ticks>
        The <ticks> value indicates how many ticks to remain on each
    frame of the animation.


BrushAnims «logical expression»

    When the «logical expression» is FALSE it stops all animations. When
it is TRUE it starts all animations.


Function

    The Function can be used in expressions to return information
relating the Brush Animation Commands.


FrameOfAnimation <integer> = FrameOfAnimation ( "BrushAnim Name" )

    The FrameOfAnimation Function returns the current frame number of the
specified "BrushAnim Name". If the Brushanim has not been loaded, the
FrameOfAnimation Function will return 0.


System Variable «logical» = AnimationStatus -TRUE if animations are currently
                    running in your window.

                                     6-41

                           Audio Scripting Commands

    The Audio Commands play Mono (non-stereo) digitized sounds. The Amiga
IFF standard for these sounds is called 8SVX. CanDo loads these sounds and
plays them through one of the four Audio Channels.


LoadSound "Filename" {, "Sound Name" }

    The LoadSound Command loads an 8SVX sampled sound. The Optional
"Sound Name" allows you to refer to it be a name other than the Filename.
Loadsound pre-loads the sound before playing it. It can then be used in a
PlaySound or PlaySoundSequence command. This command is particularly useful
for loading a sound during the Card's StartUp Script. By preloading it, there
will not be a delay the first time the sound is played.

    Examples:
        LoadSound "sounds:Laugh.snd"
        PlaySound "sounds:Laugh.snd"
        Loadsound "sounds:Bang.snd","Bang"
        PlaySound "Bang"


PlaySoundSequence "Sound Name" {, AudioFlags {, < period > } }

    The PlaySoundSequence Command plays a list of sounds. The list is
contained in a Document (see Document Commands). A Document is just like a
text editor. The PlaySoundSequence plays each "Sound Name" in the Document one
after another. Each "Sound Name" must be on a separate line. It can be file
specification or a Name created using the LoadSound Command.

    Example:
        MakeDocument "Shooting Sequence"
        Type "sounds:WatchOut.snd",NEWLINE
        Type "sounds:Bang.snd",NEWLINE
        Type "sounds:YouGotMe.snd",NEWLINE
        PlaySoundSequence "Shooting Sequence"

                                     6-42

Audio Flags

ONCE,

    which is the default, indicates the sound should only be played one
time.

    Example:
        PlaySound "Bang",ONCE


CONTINUOUS

    indicates the sound should be repeated until an AUDIO OFF Command is
executed.

    Example:
        PlaySound "Music",CONTINUOUS,600


WAIT

    When WAIT is specified, the sound begins to play when an AUDIO ON is
executed. This can be used to start multiple sounds at the same time.

    Examples:
        PlaySound "sound1",WAIT
        PlaySound "sound2",WAIT
        PlaySound "sound3",WAIT
        Audio ON


QUEUE

    Normally, a sound will only play when an Audio Channel is available
at the time PlaySound Command is performed.
    QUEUE is like telling the sound to wait in line until an Audio
Channel is available. As soon as one is, the sound will begin to play. There
is no limit to the number of sounds that can be queued.


QUEUEPREVIOUS

    is similar to QUEUE. Instead of playing on any channel, if one is
available, it will play on the same channel as the most previous sound.

    Examples:
        PlaySound "sounds:WatchOut.snd"
        PlaySound "sounds:Bang.snd",QUEUEPREVIOUS
        PlaySound "sounds:YouGotMe.snd",QUEUEPREVIOUS


< period >

    The optional period value overrides the sound's natural period/rate
saved within the 8SVX sound file. This value can range from 124, being the
fastest, to 65535 being the slowest.

                                     6-43

Setvolume < volume > , {, < channel >

    The SetVolume Command sets the volume for subsequently played sounds.
It does not change the volume of currently playing sounds.
    The Volume is an integer ranging from 0, being no volume, to 64 being
full volume.
    The Channel number is optional. When it is not specified, the
indicated volume is used for all channels. On the other hand, specifying a
channel between 0 and 3 sets the volume for a single channel.

    Examples:
        SetVolume 64
        SetVolume 32,3


SetChannel < channel >

    The SetChannel allows you to specify the channel that is used for the
next PlaySound or PlaySoundSequence command. Usually, these commands look for
any available channel. If one is available, it plays the sound.

    NOTE:
        If you are running another application that is using the
specified channel, the sound will not be palyed.


AUDIO « logical expression »

    This Command turns all Audio Channels ON or OFF. The logical
expression is evaluated to TRUE or FALSE (ON = TRUE and OFF = FALSE). When the
expression is TRUE (ON), all PlaySounds using the WAIT keyword are started.
When the expression is FALSE, all sounds (regardless of the WAIT usage) will
be terminated.

                                     6-44

                              Document Commands

    A Document is simply a data area that contains text. Using CanDo's
Memo Object, you can frad from, and type text into a Document. The List Object
allows you to select lines from a Document.
    This section describes the CanDo scripting Commands that work with
Documents. These Commands allow you to work with a Document in the same manner
as you would from a Text Editor.
    Commands such as Type, work as though you were typing characters from
a keyboard. Type "Hello World" enters the text "Hello World" into a Document.
A cursor position is maintained for each Document. Typing text into the
document occurs at the cursor position.
    Cursor movement Commands, such as 'MoveCursor LEFT 5', moves the
cursor in the document. The Delete Command remove characters at the cursor
position.
    The Commands LoadDocument and SaveDocument allow you to load and save
text files.
    The Memo and List objects show the contents of a single Document. The
Document is specified in the Document Definition Requestor in the "Document
Name" field. This makes the contents of the Document Visible in the Object.
However, you can create Documents that are not visible. These can be
particularly useful in working with text "behind the scenes". For example,
some applications may copy portions of an invisible Document into visible
Documents.
    While CanDo provides a number of Commands that work with documents,
not all are necessary for use in simple applications. This section is
organized with the most common and necessary Commands listed first. The last
part of this section describes the CanDo Variables that give information about
the current document.
    First, it is necessary to create an empty document. This is done
using the MakeDocument Command.


MakeDocument "Document Name"

    This Command creates an empty document that is identified the
"Document Name" string. The new Document becomes the Current Document. This
means Document Commands, such as Type, work with the new document.
    CanDo applications can have more than one Document. However, the
Document Commands only work with one Document at a time. The Command
WorkWithDocument Command specifies the new Current Document.

                                     6-45

WorkWithDocument "Document Name"

    This Command changes the current Document. All subsequent Document
Commands will use the indicated Document. To work with a Document that is
visible through a Memo or List Object, you should specify the name indicted in
the "Document Name" field of the Document Definition Requestor.
    If the Document specified with the "Document Name" does not currently
exist, CanDo will make a new Document with the specified name. Furthermore, it
will attempt to automatically load a file using the "Document Name" as a file
specification. If the file does not exist, it will create an empty document.
This allows you to easily create a document and load it with a file if it
exists. However, if you do not want CanDo to attempt to load a file, you must
first create the document usign the MakeDocument Command.


LoadDocument "Filename" {, "Document Name" }

    Reads the contents of the specified "Filename" into a "Document
Name". If a Document with a name of "Document Name" currently exists, it will
clear the document before loading the document.


SaveDocument "Document Name" {, "Filename" }

    The SaveDocument Command saves the specified "Document Name". When
the "Filename" is not specified, CanDo will replace the file that was
originally loaded or use the "Document Name" as a filename if the Document was
not loaded. If the "Filename" is specified, it will use it as the filename.


Type "string" {, NEWLINE }

    This Command "Type's" the string into the current Document. The
string can contain imbedded LF's for RETURNs, DELETE's and BACKSPACE's. These
characters can be created using the Char Function.

    Example:
        Type "Hello" || World

    This example concatenates the string constant "Hello" with the
contents of the variable World, and types it into the current Document.

                                     6-46

SplitLine { < count > }

    This Command is the same as a RETURN key. The optinal <count>
specifies the number of times to repeat the Command.

    Examples:
        SplitLine
        SplitLine 5


NewLine

    This Command is the same as moving the cursor to the end of the line
and pressing the RETURN key. It does not have any parameters. It is a useful
Command for creating a new line without any concern whether the cursor is
currently in the middle of a line.


MoveCursor direction {, < count > }

    Moves the cursor in the specified direction. If no count is
specified, the sursor moves once. Otherwise, it moves the direction the nymber
of times specified in the count. If the count is negative, the count moves in
the opposite direction.

    DIRECTION -You can only use one of the direction keywords.

        UP
            Moves the cursor Up. This Command has no effect
        when the cursor reaches the first line in the Document.

        DOWN
            Moves the cursor Down. This Command has no effect
        when the cursor reaches the last line in the Document.

        LEFT
            Moves the cursor Left. If the cursor is at the
        beginning of a line (and it is not the last line in the
        Document), it moves to end of the previous line.

        RIGHT
            Moves the cursor Right. If the cursor is at the end
        of a line (and it is not the last line in the Document), it
        moves to the beginning of the Next line.

    Examples:
        MoveCursor UP
        MoveCursor RIGHT,10
        MoveCursor RIGHT,RepeatCount+5

                                     6-47

MoveCursorTo location area

    This Command moves the cursor to the cursor to the start of or to the
end of the current Document, line, word, previous word, or next word.

    LOCATION -You can only use one of the direction keywords.

        STARTOF
            Indicates to move the cursor to the beginning of
        the specified Area.

        ENDOF
            Indicates to move the cursor to the end of the
        specified Area.

    AREA -You can only use one of the direction keywords.

        DOCUMENT
            Moves the cursor to the specified Location within
        the current Document.

        LINE
            Moves the cursor to the specified Location on the
        current line.

        NEXTWORD
            Moves the cursor to the specified Location on the
        word after tue current word.

        THISWORD
            Moves the cursor to the specified Location on the
        current word. If the cursor is not on a word, this Command
        will not have any effect.

        PREVIOUSWORD
            Moves the cursor to the specified Location on the
        word before the current word.

    Examples:
        MoveCursorTo STARTOF DOCUMENT
        MoveCursorTo ENDOF LINE
        MoveCursotto STARTOF NEXTWORD


PositionOnLine < line >

    Moves the cursor to the specified Line. If the specified line number
is greater than the number of lines in the Document, the cursor is placed on
the last line. The cursor offset is not effected.

                                     6-48

Clear LINE or DOCUMENT

    This Command clears either the current Line or the current Document.

    LINE
        Indicates to clear the current line. This is different than
    deleting the line. All characters are erased, but the line remains
    with the cursor in the first column.

    DOCUMENT

        Indicates to clear the current Document. This is different
    than deleting the Document. The Document still exists with all the
    characters erased.

    Examples:
        Clear LINE
        Clear DOCUMENT


Delete KeyWord {, < count > }

    This Command deletes speicfied text from the current Document. An
optional count indicates the number of times to repeat the action. (while the
syntax allows it, a count used with ToStartOfLine and ToEndOfLine has no
effect). Only one Keyword may be specified.

    KeyWord -You can only use one of the direction keywords.

    LINE
        Deletes the current Line. This removes the line completely,
    positioning the cursor at the beginning of the next line.

    TOSTARTOFLINE
        Deletes all characters before the cursor to the beginning of
    the line. (count has no effect).

    TOENDOFLINE
        Deletes all characters from the cursor to the end of the
    line. This includes the current character.

                                     6-49

    CHARACTER
        If no count is specified, a single character is deleted to
    the right of the cursor location. Otherwise, the count specifies the
    number of characters to delete. If the count is positive, then
    characters are deleted to the right of the cursor. When the count is
    negative, characters are deleted to the left of the cursor. This is
    the same as a Backspace. When the count is greater than the number of
    characters remaining on the line, the current line is concatenated
    with the next line (previous line in the case of a backspace). This
    concatenation will count as a deleted character.

    Examples:
    Delete LINE        ; Deletes a single line.
    Delete LINE 5        ; Deletes 5 lines.
    Delete TOSTARTOFLINE    ; Deletes to the beginning of a line.
    Delete CHARACTER        ; Deletes a single character.
    Delete CHARACTER 5    ; Deletes 5 characters.
    Delete CHARACTER -Repeat    ; Backspaces <repeat> times.


SearchFor "text" {, qualifiers }

    Searches for the specified string. The qualifiers allow seacrhing for
complete words and for ignoring case differences.

    Qualifiers -You can use one of both BYWORD and NOCASE.

        BYWORD
            This qualifier allows searching for complete words.
        The search will not match a string if it is a portion of a
        word.

        NOCASE
            This qualifier allow searching for a string
        ignoring case differences between the search string and the
        potential target string.

    Examples:
        SearchFor "FooMan Chew"
        SearchFor "is",BYWORD
        SearchFor "bald",NOCASE BYWORD

                                     6-50

Replace "fromtext","totext" { , { GLOBAL } { BYWORD } { NOCASE } }

    The Replace Command replaces the "fromtext" with the "totext". It wil
search forward from the current cursor location for the "fromtext". If the
"fromtext" is not found, nothing will happen. If it is found, the cursor will
be moved to the character following the new "totext".

    Qualifiers -You can use one or more qualitiers with the Replace
           Command.

    GLOBAL replace all remaining matches of the "fromtext" with the
    "totext string. When if is not specified, only one replace can
    potentially be replaced.

    BYWORD indicates the "fromtext" will match if it is contained within
    a word.

    NOCASE indicates the "fromtext" will match even if some of the
    characters are not the same. If NOCASE is not specified, it must match
    exactly.


InsertDocument "Document Name" { , < Start Line > { , < LineCount > } }

    The InsertDocument Command copies the text from the specified
"Document Name" into current document at the current cursor position. The
optional < Start Line > specifies the first line, from the "Document Name" to
copy. When it is not specified, it starts on line 1. The optional < LineCount
> indicates the number of lines to copy. If it is not specified, all lines
after the < Start Line > are copied.
    If the "Document Name" does not exist, CanDo will attempt to
automatically load it using the "Document Name" as the file specification.

    Examples:
        InsertDocument "Work Document"
        InsertDocument "S:startup-sequence"
        InsertDocument "My Resume",5
        InsertDocument "DF1:WorkFile.TXT",25,10

                                     6-51

SetWordDelimiters "delimiterlist"

    This Commands sets the word delimiter list. The word delimiters
define the characters that separate words. The default delimiters are
, ( ) ! @ # $ % ^ & * _ = + \ | < > ? / in addition to the TAB characters of
the word delimiters on both sides of the word.
    The "delimiterlist" string contains the delimitating characters for
words. This string can be any size. The beginning and ending of a line are
always word delimiters. As such, they are not explicitly in the list, but any
expression.

< Integer > = TheLineNumber     - line number the cursor is on.

< Integer > = TheColumnNumber   - column number the cursor is on.

 " String " = TheLine         - the character string for the current line.

 " String " = TheCharacter      - the character the cursor is on
                   ("" if at the end of line).

 " String " = TheWord         - the current word the cursor is on.
                   This value is based on the word delimiters.

 " String " = CharsToBegOfLine  - the characters before the cursor on the
                   current line.

 " String " = CharsToEndOfLine  - the characters from the cursor to the end of
                   the line.

< Integer > = LinesInDocument   - the number of lines on the current document.

< Integer > = LengthOfLine      - the length of the current line.

< Integer > = SizeOfDocument    - the number of bytes in the current document.

 " String " = DocumentName      - the name of the current document.

< Integer > = SizeOfDocument    - number of characters in document.

 " String " = TheWordDelimiters - the characters separating words in the
                   current document.

                                     6-52

                              File I/O Commands

    The File I/O Commands provide an easy way to write and read data from
files. CanDo uses the Amiga's Buffered I/O system for implementing these
commands. While the commands are not complicated, they are imtended for those
who are fimilar with File I/O.
    If you are mostly interested in working with text files, you might
want to consider using the Document commands.

OpenFile "filename" , "buffername" , IOFlags , AccessFlags

    Opens a file for input / output purposes. Memory is the only limit to
the number of opened files that can be open at one time. The "filename"
specifies the file to be opened. The "buffername" is a string used to identify
the buffer associated with this file access.
    The IOFlags are READONLY or WRITEONLY. READONLY indicates that you an
only read ASCII data from the file. WRITEONLY means that you can only write
ASCII data to the file.
    The AccessFlags are NEWFILE, OLDFILE or APPEND. NEWFILE indicates to
create a new file. If the specified file already exists, then it is deleted.
OLDFILE indicates to open an existing file. If it does not currently exist, it
is created. This is the DEFAULT operation. APPEND is similar to OLDFILE,
except it will position all writes to the end of the file.

    Example:
        OpenFile "t:Savedata.txt" , "Data" , READONLY , OLDFILE


FileWriteLine "buffername", "String"

    This command will output the "String" to the file referenced by the
"buffername". An important note about this command is that it will output a
linefeed at the end of each write. The file associated with the "buffername"
must have been opened in WRITEONLY mode for this command to work.

    Examples:
        FileWriteLine "Data" , "This is a Data Line."

        Let OutputData = Outputdata || "additional data"
        FileWriteLine "Data" , OutputData


FileReadLine "buffername" , VariableName

    The FileReadLine Command reads a line from a previously opened file.
It creates a string and saves it in the specified VariableName. A line from
the file is defined to be a string terminated with a line feed.

    Example:
        FileReadLine "Data File" , DataLine

                                     6-53

FileReadChars "buffername" , VariableName , < NumberOfChars >

    This command reads a specified number of characters, <NumberOfChars>,
from a previously opened file, "buffername". These characters are stored in
the VariableName.

    Example:
        FileReadChars "Input File" , FiveChars , 5


FileWriteChars "buffername" , "String" { , < length > }

    This command will output the characters contained in "string" to the
file associated with the "buffername". This command differs from the
FileWriteLine in that this command will NOT output a linefeed after each
write. The referenced file must have been previously opened in WRITEONLY.
There is an optional argument that specifies how many characters to output. If
the length specified is greater than the length of "expression" is shorter
than the specified <length>, spaces are NOT concatenated to the string.

    Example:
        FileWriteChars "Data",Outdata || spaces, 20

SetFileBufferSize < sizeinkilos >

    This command sets the file input / output buffer size in kilobytes.
The default for the buffer size is four (4) kilobytes. A value of 8, allocates
8192 byte buffer. The buffer size is set on a file basis. This command only
changes the buffer size files opened after the command is issued.

    Example:
        SetFileBufferSize 2
        OpenFile "t:WorkFile.dat" , "WorkData" , READONLY , OLDFILE


Close "buffername"

    This command closes the file associated with the specified Data Name.
The 'Flush' command performs the same function when used with a "buffername".
Any buffered changes that you have made to the file will be written to the
file at this time.

                                     6-54

                                Icon Commands

    Most application programs on the Amiga have a file that goes with
them called an icon file. All such icon files end with the letters ".info".
These files contain imagery that Workbench uses to display a visual
representation of the application on the Workbench screen of in various
Workbench windows. Most diskettes and many data files also have icon files.
With CanDo, you can easily create, examine, and modify icons without knowing
any of the details of the icon file internal format.


LoadIcon "filename" { , "Name" { , < load flags > } }

    Loads the icon for the "filename" into memory. The extension of
".info" is automatically appended to the filename. Therefore, to load the icon
for CanDo you would type, LoadIcon "CanDo". Any valid Amiga icon can be loaded
with the command, althought only Project and Tool icons can be created using
the MakeIcon Command.


SaveIcon "Icon Name" { , "filename" }

    This command saves the icon buffer "Icon Name" as the icon for the
"filename" indicated. The extension of ".info" is automatically appended to
the filename. This command will overwrite any icon that already exists for the
"filename". If the "filename" parameter is not included, CanDo will save the
file using the original file name or use the "Icon Name" as the file
specification if it was created using the MakeIcon Command.
    If the icon "Icon Name" is not already in memory, it will be loaded
and then saved, so you can easily copy an icon from disk to a new name without
first loading it.

    Example:
        SaveIcon "fred","ram:Jack"
        Fluse "fred"

    This script would load the icon file "fred.info" from disk (assuming
it was not already in memory) and save it into a file called "ram:Jack.info".
The "fred" icon buffer in memory would then be flused.

                                     6-55

MakeIcon "Icon Name" , PROJECT or TOOL , "ImageName" { , "AltImageName" }

    This command creates an icon buffer with the given "Icon Name". You
must specify whether this icon is to be a PROJECT or a TOOL icon (explained
below), and you must indicate a Brush to use for the image of the icon. In
addition, you may specify a Brush buffer to use for the highlight of the icon
when it is clicked on with the mouse on Workbench. If you do not specify an
AltImage Brush, the icon will complement when clicked. If either the
"ImageName" or the "AltImageName" brushes are not in memory currently, they
will be loaded from disk and buffers for them will be created using the
indicated names.
    Once an icon has been created in this way, it can be saved to disk
with the SaveIcon Command.

    Examples:
        MakeIcon "MyProject" , PROJECT , "Brushes:WorkIcon.br"

        MakeIcon "MyProject" , PROJECT , "Brushes:WorkIcon1.br" ,
            "Brushes:Tools2.br"


SetDefaultTool "Icon Name" , "DefaultTool"

    This command sets the Default Tool of the icon "Icon Name". If "Icon
Name" is not already in memory, it will be loaded. The Default Tool of an icon
is the application that will be run if the icon is double-clicked on Workbench
and is itself not an application. For example, many paint programs make icons
for the pictures and brushes that they save. When the icon is double-clicked
the paint program that make the icon is launched an it then loads the picture.
    By using the Info menu command from the Workbench, you can see the
various default tools specified by icons on your Amiga.
    When choosing a default tool for icons you create or modify with
CanDo, it is important to be sure that those applications properly deal with
being run from the Workbench environment. CanDo and all of your applications
made with CanDo can run equally well from CLI and Workbench.


SetIconImage "Icon Name" , "ImageName" { , "AltImageName" }

    SetIconImage changes the image for "Icon Name" to the Brush
"ImageName", and, if the "AltImageName" is supplied, will also set the
highlight of the icon to that image. If the "AltImageName" is not supplid, the
current highlight mode for the icon will not be changed. If the "Icon Name",
or either of the Brushes, is not in memory it will be loaded into memory and
will be given the indicated names.
    Note; that the size of the "hit area" of the icon will be changed to
reflect the size of the "ImageName" used in this command.

                                     6-56

InsertToolTypeList "Icon Name"

    This command TYPEs into the current Document all of the ToolTypes for
the "Icon Name" (see Document commands). A ToolType is any ASCII string that
contains information about any subject you like. By using the Info command
from Workbench on the CanDo icon, you will see that it uses many ToolTypes to
control the default configuration for CanDo. (These ToolTypes can also be set
through the Workbench Info command).
    By performing this command when your CanDo application starts, you
can let your user specify information which your application can use while
running. For example, you could create a single-card application called
"Viewer" that performed the following script in its AfterStartup script:

    LoadIcon TheOriginDirectory || "Viewer"  ;load our own icon
    MakeDocument "pictures"
    InsertToolTypeList             ;get the filenames
    MoveCursorTo StartOf Document

    While TheLine <> ""             ;continue until a blank line
        If FileType(TheLine)="pictuers" ;make sure it's OK
            ShowPicture TheLine    ;show it if so

            Delay 0,10,0         ;wait for a sec
        Endif

        MoveCursor Down             ;go to the next line
    EndLoop

    This is a slide-show program created with CanDo in the amount of time
it takes you to type in the abouve script. The user just puts the name of the
picture files to show info the icon using the Workbench Info command and then
runs your program.


SetToolTypeList "Icon Name" , "DocumemtName"

    This command takes each line from the indicated Document and makes it
part of the "Icon Name"'s ToolType list. See InsertToolTypeList above for a
discussion of the function and merits of ToolTypes.


Icon Functions

    These Functions can be used in expression to return information
relating to the Icon Commands.


DefaultTool    "String" = DefaultTool ( "Icon Name" )

    The DefaultTool Function returns the default tool for the icon
buffer. See the SetDefaultTool Command for more information about DefaultTool.


IconType        "String" = IconType ( "Icon Name" )

    The IconType return the icon type for the "Icon Name". If returns a
string indicating the Type. It returns one of the following: "Project",
"Disk", "Drawer", "Tool", "NDOS", "Device", "KickStart", and "Uknown".

                                     6-57

                                ARexx Commands

    ARexx is a high-level language developed be Wiliam Hawes.
Applications supporting ARexx offer standardized communications using Amiga
Public Message Ports. An application can create a Public Message Port for
receiving ARexx messages. A Port created for this purpose is referred to as an
ARexx Port.
    CanDo does not internally support ARexx's interpreted language; CanDo
supports ARexx communications. While the ARexx language itself can be a
powerful enhancement to your Amiga, it is not required for your CanDo
application to utilize ARexx communication.
    Your application can send or receive ARexx messages, or do both. To
receive messages, you need to create an ARexx Port using the ListenTo command.
By putting this command in the Startup script of your first Card, you can be
sure you are ready to receive messages in the Port. The CanDo's ARexx Objects
allow you to look for specific messages received by the Port. After receiving
a message, a script can use the System Variable TheMessage to examine the full
text of the message.
    CanDo can also send messages to other applications that support
ARexx. The SpeakTo Command tells CanDo the name of the ARexx Port belonging to
the application with which you want to communicate. The SendMessage Command
sends a message to the application through this Port. You can optionally
receive Results from the application. When sending a message to another
application, you should consult its documentation regarding its ARexx Port
name and valid message commands. Of course, you can design your own
applications using CanDo that communicate using ARexx.


SpeakTo "PortName"

    This Command tells CanDo the name of the ARexx Port to send messages
to. All subsequent SendMessage Commands will send messages to the specified
"PortName".

                                     6-58

SendMessage "MessageText" ( , NORESULTS )

    The SendMessage Command sends the "MessageText" to the "PortName"
specified in the most previously executed SpeakTo Command. The optional
keyword, NORESULTS, indicates that the application does not return a text
message. If NORESULTS is not specified, the System Variable MessageReturned
will contain the returned message.
    The System Variable MessageErrorCode will contain an error code
returned by the application. By convertion, a ZERO indicates it completed the
operation. A non-zero value is an application specified error code.

    Example:
        SpeakTo "Widget"
        SendMessage "Do Your Job"
        If MessageErrorCode <> 0
            GoToCard "ErrorCard"
        Endif

    This example first tells CanDo to send messages to an application
that has an ARexx Port with a name of "Widget". If then sends the message "Do
You Job". The System Variable will not be equal to 0 (Zero) if the application
returned an error condition. This script would cause your CanDo application to
go to a Card caled "Error Card".


ListenTo "PortName"

    This command specifies the name of the "PortName" for receiving
messages. This is the Public Message Port through which your ARexx Port, CanDo
will create a Public Message Port by the specified name. If you are changing
the ListenTo "PortName", the old "PortName" will no longer exist. It is
considered good practice for your application to have only one "PortName" for
receiving messages.


InsertMessagePortList

    This command TYPE's the list of all Public Message Ports into the
current Document (see Document Commands). Each Port name will be on its own
line. Because there are Public Message Ports that do not support ARexx
messages, you should not haphazardly send messages to just any port in the
list. Sending a message to a non-ARexx Port can cause the Amiga to crash.

     "String" = CurrentListenTo  - "PortName" of most recent ListenTo.

     "String" = CurrentSpeakTo   - "PortName" of most recent SpeakTo.

    <Integer> = MessageErrorCode - Error Code from previous Return
                    message.

     "String" = MessageReturned  - Most recent Return message.

     "String" = TheMessage      - Last message received through
                    ListenTo.

                                     6-59

                               Object Commands

    The Object Commands effect various Objects created with CanDo. Many
of these commands use an "Object Name" as a parameter. The "Object Name"
should coorespond to the Name specified in an OBJECT'S EDITOR (see Objects
Documentation for more information).


DisableObject "Object Name"

    The "Object Name" identifies a Button, Field, or Document Object.
This command will make the Object inaccessabel to the user of your application
and the Object will be displayed as ghosted.


EnableObject "Object Name"

    This command will make the Object accessable to the user of your
application and will display the Object as non-ghosted. Note that simply
enabling certain types of Objects is not enough to ensure that their
appearance is the way you want is to be. This can be especially true for
Fields and Area Buttons. In these cases, a ClearWindow Command may be
appropriate to use after the EnableObject Command.


SetObjectState "Object Name" , « logical expression »

    This command can be used to deselect or select a Button, Field, or a
Memo Document. When the « logical expression » is TRUE, it will select the
Object. When it is FALSE it will deselect the Object. For Buttons, selection
means that the highlighted form of the Button's display is shown in the
window. For Fields and Memos, selection means that this Object will receive
keyboard input and a cursor will apear in the Object's hit area.


FastFeedBack « logical expression »

    The FastFeedBack Command enables or disables fast feedbask of mouse
movement for an Object's Drag Script. The Drag Script is performed while the
left mouse button is pressed and moved over a selected Object. Each time the
mouse is moved, the Drag Script is performed. It is possible for the mouse to
move several times while the Drag Script is being performed.
    When FastFeedBack is disabled, the Drag Script is performed for every
mouse movement, including the movements that could not be performed while a
script is being performed. This has the benefit of having the script performed
at each point in a path. However, this will cause the execution of a script to
fall behind the current location of the mouse pointer.
    When FastFeedBack is enabled, the Drag script will skip up to 20
mouse movements that occurr while a script is being performed. This allows the
script execution to keep up with mouse movement. However, this means it will
potentially miss some of the points along the path.
    If the « logical expression » is TRUE, the fast feedback is enabled.
Otherwise, it is disabled.

                                     6-60

MoveObject "Object Name" , < X > , < Y >

    The MoveObject Command moves a visible Object in your window. You can
use the MoveObject Command to move Buttons, Fields, and Documents. The "Object
Name" is the name specified in the Object's Editor. The <X>,<Y> values are the
horizontal and vertical coordinates where you want to move it to. NOTE; it is
possible to move the object off the visible portion of your window.


SetInteger "Object Name" , < value >

    The SetInteger Command sets the value displayed in the Integer Field
indicated by the "Object Name". The "Object Name" is the name specified in the
FIELD EDITOR REQUESTER. The <value> is the integer value to put into the
field. The Minimum and Maximum range for this value will be controlled by the
Limits as Defined in the Field Editor Requester for this field.


SetText "Object Name" , "Text"

    The SetText Command sets the string displayed in the String Field
indicated by the "Object Name". The "Object Name" is the Name specified in the
FIELD EDITOR REQUESTER. The "Text" is the string value to put into the field.
No more than the Maximum Number Of Characters (as defined in the Field Editor
Requester) will be copied into the field.


IntegerFrom    <Integer> = IntegerFrom ( "Object Name" )

    The IntegerFrom Function returns the integer currently displayed in
an Integer Field. The < Integer > value is guaranteed to be between the
Maximum and Minimum values specified in the INTEGER FIELD REQUESTER.


TextFrom         "String" = TextFrom ( "Object Name" )

    The TextFrom Function returns the string currently displayed in Text
Field. The "Object Name" is the name specified in the FIELD EDITOR REQUESTER.


ObjectState     «logical» = ObjectState ( "Object Name" )

                                     6-61

                               Buffer Commands

    The data CanDo uses is stored in area of memory called a Buffer.
Every Picture, Brush, BrushAnim, Document, Sound, File I/O, and Icon, is kept
in a Buffer. CanDo "manages" these buffers for you automatically. This
automatic system is designed to relieve the novice user fram concern about
what can be a complicated problem. For this reason, it is not necessary for
all CanDo users to concern themselves with using the Buffer Commands. However,
these commands are provided for the users who may want to change the way the
automatic system works.
    Each Buffer has a unique name. The name is simply a "String"
identifying the Buffer. Most of the time, the name is the file specification
from which the data was loaded. This is the case when a ShowBrush Command
needs to load the image before showing it. However, the LoadBrush Command
allows you to provide some other Buffer Name. (Note: most of the documentation
avoids the terminology "Buffer" because it would make it seem unnecessarily
complicated).
    CanDo keeps track of each Buffer's Name, Data, the file specification
if the Data came from a file, the Buffer Type, whether it is currently being
used and if the data has been modified. The purpose of this is to manage the
memory used by a buffer.
    Memory is a scarce resource that is in constant demand. The types of
operations made easy by CanDo canbe a nightmare of details for a programmer in
another language. For example: when a picture is to be displayed, memory must
be allocated from a "Pool" that is available to all programs. The picture is
loaded from a file that was created in a standard format known as IFF. The IFF
data is loaded from the file and converted to a form that the Amiga Hardware
can use for displaying the image. For the image to be displayed, it must be
put into the Amiga's Chip memory. There is a separate Pool for Chip memory.
When the picture is done being displayed, its memory is given back to the
Pool.
    Some of the difficulty occurs when there is not enough memory in one
of the Pools. There are ways to tell the Amiga Operation System give back
memory that it is not using any more. If there still is not enough memory, the
program needs to look for memory it has allocated from the Pool and is not
currently being used.
    When CanDo can not get enough memory from a Pool to complete an
operation, it looks through the Buffers and returns as much memory as it can.
If the Buffer's Data is not currently being used and it has not been modified.
CanDo returns the memory being used by the Buffer's Data. However, it keeps
all of the other information about the Buffer.
    By keeping the Buffer information and not its data, CanDo can
automatically reload the data from the file if it ever needed again.

                                     6-62

SetAutoLoadFlags ( CHIP and ASNEEDED ) or NONE

    The LoadFlags Appendix describes how you can control on a file by
file basis how CanDo keeps the file in memory. However, many of the files are
automatically loaded without a load command. This is done with commands such
as ShowBrush and PlaySound. Files are also loaded by some of CanDo's Objects
such as Image Buttons and Picture Windows.
    The SetAutoLoadFlags Command allows you to use the loadflags ASNEEDED
and CHIP for files that are automatically loaded. When ASNEEDED is indicated,
CanDo automatically returns the Buffer's Data as soon as it is not being used.
The CHIP keyword indicates the file should be loaded directly into the Amiga's
Chip memory. While having the Data in Chip running completely out of memory.
By default the AutoLoadFlags are NONE.

    Examples:
        SetAutoLoadFlags ASNEEDED

        SetAutoLoadFlags CHIP

        SetAutoLoadFlags CHIP ASNEEDED

        SetAutoLoadFlags NONE


Flush "Buffer Name"

    The Flush Command frees all memory used be the specified "Buffer
Name". This causes CanDo to forget everything about the Buffer as though it
was never created. If you Flush a buffer that is curently being used, CanDo
will Flush it as soon as it can.

    Example:
        LoadBrush "brushes:theimage.grab","arrow"
        ShowBrush "arrow",50,50
        Flush "arrow"


FlushAll

    This command flushes all Buffers. Buffers that are currently being
used will be flushed as soon as they can be safely flushed.


RamScram

    This causes CanDo to free all Buffer Data that is not being nused and
has not been modified. Unlike Flushing a buffer, it does not cause CanDo to
forget the buffer completely. This way the Data can be automatically loaded if
it is needed again.

                                     6-63

InsertChangedBufferList

    This command TYPE's the name of all modified buffers into the current
Document (see Document Commands). Each Buffer Name will be on a separate line.


SaveAllChangedBuffers

    This causes CanDo to save all buffers that have been modified. If the
Data was originally loaded from a file, it will be saved using the original
file specification. Otherwise, it will use the Buffer Name as the file
specification.


GetBufferInfo "Buffer Name" , Var1 { , Var2 { , Var3 { , Var4 } } }

    This command returns information about the specified "Buffer Name".
This Command only supports the Buffer Type of Picture, Brush, BrushAnim,
Sound, and Documents. The Var1 through Var4 specifies the variable names that
should be set to the buffer information. Each of the valid Buffer Types sets
the variables to a specialized piece of information for the specific Type.
These are outlined below:

    Buffer Type    Var1    Var2         Var3     Var4
    ------------------------------------------------------------------
    Picture        Width    Height         Depth
    Brush        Width    Height         Depth
    BrushAnim    Width    Height         Depth     # of frames
    Sound        Samples    Seconds         Sample Rate
    Documents    Lines    Longest Line  Size

    Examples:
        GetBufferInfo "Images:Man.pic",PicWidth,PicHeight,
                  NbrOfBitPlanes

        GetBufferInfo "Sounds:Howl.snd",Samples,Time,Rate

                                     6-64

Functions

    This Function can be used in expressions to return information
relating to the Buffer Commands.


BufferType     "String" = BufferType ( "Buffer Name" )

    This function returns the BufferType for the specified "Buffer Name".
The BufferType are: "Brush", "BrushAnim", "Document", "Icon", "Picture","Read
File", "Write File", and "Sound". If the "Buffer Name" is not found,
BufferType will return a NULL ("") string.


System Variables    «logical» = AnyChangedBuffers - TRUE if there are any
                         modified Buffers.

                                     6-65

                                Misc Commands

    This last section contains various other commands relating to overall
control of the Amiga and of your applications.


Pointer « logical expression »

    This command turns on or off mouse pointer. When the «logical
expression» value is TRUE, the image is turned on. When it is False, it is
turned off.


SetPointer "Brush Name" [ , < X > , < Y > ]

    This command allows you to use a DPaint style brush as the mouse
pointer. It canbe up to 16 pixels wide, and as tall as 127 pixels. If it is
larger than these dimensions, only the leftmost and topmost part of the image
will be used. The Optional <X>,<Y> offset specifies the "hotspot" for the
pointer. Otherwise, it will assume it is located at 0,0.
    Color Registers 17,18, and 19 are used both for displaying an image
and for the mouse pointer.

    Example:
        SetPointer "Brushes:HandImage.br",5,5


Dos "DOS Command"

    The Dos Command executes the string specified in "DOS Command" as an
AmigaDOS Command. This works as though you typed the command from a CLI
window.

    Example:
        Dos "run c:dir >RAM:Temp.txt"


SetCurrentDirectory "directory path"

    This Command sets your applicaton's default directory. This command
affects file specifications that do not include "device:" portions. It also
sets the initial default directory for applications invoked using the Dos
Command. Many applications use this default directory for identifying their
environment.

                                     6-66

Delay < mm > , < ss > , < jj >

    The Delay Command causes a delay in the execution if the script. The
values indicate the number of minutes, seconds, and jiffies to delay. The
script continues to execute after the delay.
    Note; while a script is being executed, no other object's scripts can
be processed. This prevents any Buttons, Menus, e.t.c... from executing a
script. Because the delay cannot be interrupted, an excssively long delay will
prevent you from exiting a script until the delay has elapsed.
    The <mm> value indicates the number of minutes, the <ss> indicates
the number of seconds, and the <jj> indicates the number of jiffies to delay.
(U.S. Amigas use 1/60 of a second for jiffies, and PAL Amigas use 1/50 of a
second).

    Examples:
        PrintText 50,50,"Taking a 6 second breather."
        Delay 0,6,0

        PrintText 50,50,"Taking a One minute break."
        Delay 1,0,0

        PrintText 50,50,"Hold for a half a second."
        Delay 0,0,30


Echo "Text" { , NOLINE }

    The Echo Command prints a text message if CanDo or your application
was starte from a CLI. This can be useful for making CLI application or
displaying debugging information.

    Examples:
        Echo "Print on my CLI Window"
        Echo "Variable Count = " || Count


InsertDeviceList LOGICAL PHYSICAL ASSIGNS ALL

    This command TYPE's the list of Devices into the current Document.
The keyword LOGICAL returns the logical names of all mounted devices. PHYSICAL
returns the physical device names (i.e. DF0:, DF1:). ASSIGN returns all system
assignments. ALL returns all LOGICALS, PHYSICALS, and ASSIGNMENTS.

    Examples:
        MakeDocument "System Assignments"
        InsertDeviceList ASSIGNS

        MakeDocument "All Devices"
        InsertDeviceList ALL

                                     6-67

InsertDirectoryList { FILEONLY or DIRECTORIESONLY }

    This command TYPE's the Directory listing for the Current Directory
(see SetCurrentDirectory). The optional keyword FILESONLY excludes directories
from the directory listing. DIRECTORIESONLY returns only the sub-directories
in the Current Directory.

    Examples:
        MakeDocument "System Directory"
        SetCurrentDirectory "SYS:"
        InsertDirectoryList

        MakeDocument "Font List"
        SetCurrentDirectory "Fonts:"
        InsertDirectoryList DIRECTORIESONLY


InsertStartingMessage

    The InsertStartingMessage Command is used to get the parameters used
for starting an application. If it was started from Workbench using an Icon,
it will TYPE the full pathnames of all other icons that were selected at the
time your application was started into the currrent Document. (A user of your
program could select five icons and then start your program. With this
command, you would get the names of the five files referred to by those five
icons). If your application was run from CLI, this command TYPE's each of the
parameters on the command line. Any parameters enclosed in double-quotes will
be treated as single parameters. They will have the double-quotes removed and
internal any doubled double-qoutes ("") will be reduced to single
double-qoutes.
    NOTE: When developing your application from CanDo, this command will
insert the starting message for CanDo. After all, CanDo started your program
after itself having been started. When running your applications separately,
however, InsertStartingMessage will insert the starting message to your
application.

    «logical» = StartedFromWorkbench - TRUE when started from Workbench.

     "String" = TheCommandLine       - Returns the command line if
                        started from CLI, otherwise a NULL
                        string.

     "String" = TheCurrentDirectory  - Returns your application's current
                        directory.

     "String" = TheOriginDirectory   - This is the directory your program
                        started running from.

                                     6-68

                                  Chapter 7

                                  Appendices

Commands Index

Page            Command

6-11 <Integer> =    Absolute ( <value> )
6-41 «Logical» =    AnimationStatus
6-65 «Logical» =    AnyChangedBuffers
6-28        AreaCircle <x>,<y>,<r>
6-28        AreaEllipse <x>,<y>,<xr>,<yr>
6-28        AreaRectangle <x>,<y>,<w>,<h>
6-12 <Integer> =    ASCII ( "string" )
6-44        Audio «logical expression»
6-17 <Integer> =    AvailableChipMemory
6-17 <Integer> =    AvailableFastMemory
6-17 <Integer> =    AvailableMemory
6-41        BrushAnims «logical»
6-65 "String"  =    BufferType ( "Buffer Name" )
6-16 "String"  =    BumpRevision ( "Name" )
6-17 "String"  =    CardName
6-12 "String"  =    Char ( <integer> )
6-52 "String"  =    CharsToBegOfLine
6-52 "String"  =    CharsToEndOfLine
6-49        Clear LINE or DOCUMENT
6-31        ClearWindow { <color> }
6-26        ClipBrush <x>,<y>,<width>,<height>,"Brush Name" {, CHIP }
6-26        ClipPicture "Picture Name" {, CHIP }
6-34 <Integer> =    ClipTransparentColor
6-54        Close "Buffer Name"
6-34 <Integer> =    ColorOfPixel ( <x>,<y> )
6-59 "String"  =    CurrentListenTo
6-59 "String"  =    CurrentSpeakTo
6-32        CycleColors <From-Color>,<To-Color> {, FORWARD or BACKWARD }
6-17 "String"  =    DeckName
6-57 "String"  =    DefaultTool ( "Icon Name" )
6-67        Delay <mm>,<ss>,<jj>
6-49        Delete KeyWord {, <count> }
            KeyWord: TOSTARTOFLINE, TOENDOFLINE, or CHARACTER
6-60        DisableObject "Object Name"
6-21        Do "routine name" {, Arg1, ..., Arg10 }

                                     7-1

6-52 "String"  =    DocumentName
6-66        Dos "DOS Command"
6-29        DrawCircle <x>,<y>,<r>
6-29        DrawEllipse <x>,<y>,<xr>,<yr>
6-29        DrawLine <x1>,<y1>,<x2>,<y2>
6-29        DrawPixel <x>,<y>
6-30        DrawRectangle <x>,<y>,<w>,<h>
6-30        DrawTo <x>,<y>
6-13 "String"  =    DupeString ( "String", <count> )
6-67        Echo "Text" {, NOLINE }
6-60        EnableObject "Object Name"
6-16    result =    EvaluateExpression ( "String" )
6-20        ExitLoop
6-22        ExitScript
6-17 «Logical» =    FALSE
6-60        FastFeedBack «Logical Expression»
6-54        FileReadChars "Buffer Name", VariableName, <NumberOfChars>
6-53        FileReadLine "Buffer Name", VariableName
6-54        FileWriteChars "Buffer Name", "String" {, <lenght> }
6-53        FileWriteLine "Buffer Name", "String"
6-29        FillToBorder <x>,<y>,<BorderColor>
6-14 <Integer> =    FindChars ( "Source", "Search", <staring offset> )
6-15 <Integer> =    FindWord ("Source", "Search Word" {, <StartWordNumber> {,
            "Worddelimiters" } } )
6-23        FirstCard
6-28        FloodFill <x>,<y>
6-63        Flush "Buffer Name"
6-63        FlushAll
6-41 <Integer> =    FrameOfAnimation ( "BrushAnim Name" )
6-39        GetBrushAnimCoordinates "BrushAnim Name",Xvariable,Yvariable
6-64        GetBufferInfo "Buffer Name", Var1 {,Var2 {,Var3 {,Var4 }}}
6-15 "String"  =    GetChars ( "Source", <starting offset>, <length> )
6-31        GetRGB <col.reg>, RedVar, GreenVar, BlueVar
6-34        GetTextDimensions "Text", Width-Variable, Height-Variable
6-15 "String"  =    GetWord ( "Source", <WordNumber> {, "WordDelimiters" } )
6-23        GotoCard "Card Name"
6-37 «Logical» =    Hires
6-57 "String"  =    IconType ( "Icon Name" )
6-18        If «Logical Expression» ... Else ... EndIf
6-64        InsertChangedBufferList
6-14 "String"  =    InsertChars ( "Source", "Destionation", <offset> )
6-67        InsertDeviceList LOGICAL, PHYSICAL, ASSIGNS, ALL

                                     7-2

6-68        InsertDirectoryList { FILESONLY or DIRECTORIESONLY }
6-51        InsertDocument "Document Name"{,<Start Line>{,<LineCount> }}
6-59        InsertMessagePortList
6-68        InsertStartingMessage
6-57        InsertToolTypeList "Icon Name"
6-10 <Integer> =    Integer ( Expression )
6-61 <Integer> =    IntegerFrom ( "Object Name" )
6-37 «Logical» =    InterLace
6-17 <Integer> =    LargestChunkOfMemory
6-23        LastCard
6-52 <Integer> =    LengthOfLine
6-05        Let VariableName = Expression
6-11 <Integer> =    Limit ( <limit1>, <limit2>, <test value> )
6-52 <Integer> =    LinesInDocument
6-59        ListenTo "Port Name"
6-24        LoadBrush "filename" (, "Name" (, loadflags ) )
6-38        LoadBrushAnim "filename" (, "BrushAnim Name" {, loadflags } )
6-46        LoadDocument "filename" (, "Document Name" )
6-55        LoadIcon "filename" (, "Name" { <loadflags> } )
6-24        LoadPicture "filename" (, "Name" {, <loadflags> } )
6-42        LoadSound "filename" (, "Sound Name" )
6-10 «Logical» =    Logical ( Expression )
6-19        Loop ... Until «Logical Expression»
6-20        Loop ... EndLoop
6-13 "String"  =    LowerCase ( "String" )
6-45        MakeDocument "Document Name"
6-56        MakeIcon "Icon Name", PROJECT or TOOL, "ImageName" {,
            "AltImageName"}
6-11 <Integer> =    Max ( <val>, <val>, ... )
6-17 <Integer> =    MaxInteger
6-59 <Integer> =    MessageErrorCode
6-59 "String"  =    MessageReturned
6-11 <Integer> =    Min ( <val>, <val>, ... )
6-17 <Integer> =    MinInteger
6-37 <Integer> =    MouseX
6-37 <Integer> =    MouseY
6-39        MoveBrushAnim "BrushAnim Name", <Xvel>, <Yvel>, { <Xacc>,
                 <Yacc>, { <ticks> } }
6-38        MoveBrushAnimTo "BrushAnim Name", <x>, <y> {, <ticks> }
6-47        MoveCursor UP DOWN LEFT or RIGHT {, <Count> }
6-48        MoveCursorTo Location Area
           Location: STARTOF or ENDOF
           Area    : DOCUMENT,LINE,NEXTWORD,PREVIOUSWORD,or THISWORD

                                     7-3

6-61        MoveObject "Object Name", <x>, <y>
6-30        MovePen <x>, <y>
6-35        MoveScreen <Delta-X>, <Delta-Y>
6-36        MoveWindow <Delta-X>, <Delta-Y>
6-47        NewLine
6-23        NextCard
6-17 «Logical» =    NO
6-37 «Logical» =    NTSC
6-13 <Integer> =    NumberOfChars ( "String" )
6-17 "String"  =    ObjectName
6-61 «Logical» =    ObjectState ( "Object Name" )
6-17 «Logical» =    OFF
6-17 «Logical» =    ON
6-53        OpenFile "filename", "Buffer Name", IOFlags, AccessFlags
           IOFlags    : READONLY or WRITEONLY
           AccessFlags: NEWFILE, OLDFILE, or APPEND
6-34 <Integer> =    PenA
6-34 <Integer> =    PenB
6-34 <Integer> =    PenO
6-42        PlaySound "Sound Name" {, AudioFlags, <period> }
6-42        PlaySoundSequence "Document Name" {, AudioFlags, <periode> }
6-66        Pointer «Logical Expression»
6-16 <Integer> =    PositionOfWord ( "Source",<WordNumber>,{,"WordDelimiters"} )
6-48        PositionOnLine <line>
6-23        PreviousCard
6-33        PrintText <x>, <y>, "String"
6-22        Quit
6-63        RamScram
6-12 <Integer> =    Random ( <Minimum>, <Maximum> )
6-30        RayTo <x>, <y>
6-39        RemoveBrushAnim "BrushAnim Name"
6-14 "String"  =    RemoveChars ( "Source", <starting offset>, <length> )
6-51        Replace "fromtext","totext"{,[GLOBAL or ONCE] BYWORD NOCASE}
6-64        SaveAllChangedBuffers
6-27        SaveBrush "Brush Name" (, "filename" )
6-46        SaveDocument "Document Name" (, "filename" )
6-55        SaveIcon "Icon Name" (, "filename" )
6-27        SavePicture "Picture Name" (, "filename" )
6-37 <Integer> =    ScreenColors

                                     7-4

6-37 <Integer> =    ScreenHeight
6-35        ScreenTitleBar «Logical Expression»
6-35        ScreenTo FRONT or BACK
6-37 <Integer> =    ScreenWidth
6-37 <Integer> =    ScreenX
6-37 <Integer> =    ScreenY
6-50        SearchFor "text" {, BYWORD and NOCASE }
6-59        SendMessage "MessageText {, NORESULTS }
6-31        SetAreaDrawMode NORMAL or OUTLINE
6-63        SetAutoLoadFlags [ CHIP and ASNEEDED ] or NONE
6-40        SetBrushAnimFlags "BrushAnim Name",<brushanimflags>{,<ticks>}
           COMPRESSEDMODE or DECOMPRESSEDMODE
           RESTOREBACKGROUND or LEAVEIMAGE
           USEMASK or NOMASK
           SEQUENCEDMOTION or LINEARMOTION
           FORWARD, BACKWARD and PINGPONG
           NONE
6-44        SetChannel <channel>
6-26        SetClipTransparentColor <color>
6-66        SetCurrentDirectory "directory path"
6-56        SetDefaultTool "Icon Name", "DefaultTool"
6-31        SetDrawMode NORMAL JAM1 JAM2 COMPLEMENT INVERSEVIDEO
6-54        SetFileBufferSize <sizeinkilos>
6-56        SetIconImage "Icon Name", "ImageName" {, "AltImageName" }
6-61        SetInteger "Object Name", <value>
6-60        SetObjectStart "Object Name", «Logical Expression»
6-32        SetPen <penA> {, <penB> {, <penO> } }
6-66        SetPointer "Brush Name" {, <x>, <y> }
6-33        SetPrintFont "fontname", <pointsize>
6-33        SetPrintStyle StandardFlags { ExtendedFlags {, <ExtPen1> {,
                 <ExtPen2> } } }
           StandardFlags: PLAIN ITALIC BOLD and UNDERLINED
           ExtendedFlags: SHADOW OUTLINE GHOSTED or EMBOSSED
6-32        SetRGB <col.reg>, <red>, <green>, <blue>
6-35        SetScreenTitle "Text"
6-61        SetText "Object Name", "Text"
6-57        SetToolTypeList "Icon Name", "Document Name"
6-44        SetVolume <volume> {, <channel> }
6-36        SetWindowLimits <MinX>, <MinY>, <MaxX>, <MaxY>
6-36        SetWindowTitle "Text"
6-52        SetWordDelimiters "delimiterlist"
6-25        ShowBrush "Brush Name", <x>, <y> {, BRUSHPALETTE }

                                     7-5

6-38        ShowBrushAnim "BrushAnim Name", <x>, <y>
6-27        ShowPalette "file specification"
6-25        ShowPicture "Picture Name"
6-12 <Integer> =    Sign ( <value> )
6-52 <Integer> =    SizeOfDocument
6-58        SpeakTo "PortName"
6-47        SplitLine { <count> }
6-68 «Logical» =    StartedFromWorkbench
6-22        StopScript
6-10 "String"  =    String ( Expression )
6-17 «Logical» =    Supervised
6-61 "String"  =    TextFrom ( "Object Name" )
6-52 "String"  =    TheCharacter
6-52 <Integer> =    TheColumnNumber
6-68 "String"  =    TheCommandLine
6-68 "String"  =    TheCurrentDirectory
6-17 "String"  =    TheDate
6-52 "String"  =    TheLine
6-52 <Integer> =    TheLineNumber
6-59 "String"  =    TheMessage
6-68 "String"  =    TheOriginDirectory
6-17 "String"  =    TheTime
6-52 "String"  =    TheWord
6-52 "String"  =    TheWordDelimiters
6-26        Transparent «Logical Expression»
6-34 «Logical» =    TransparentStatus
6-13 "String"  =    TrimString ( "String" )
6-17 «Logical» =    TRUE
6-46        Type "String" {, NEWLINE }
6-13 "String"  =    UpperCase ( "String" )
6-17 «Logical» =    VerifyExpression ( "String" )
6-20        While «Logical Expression» ... Until «Logical Expression»
6-19        While «Logical Expression» ... EndLoop
6-37 <Integer> =    WindowColors
6-37 <Integer> =    WindowHeight
6-37 "String"  =    WindowTitle
6-36        WindowTo FRONT or BACK
6-37 <Integer> =    WindowWidth
6-37 <Integer> =    WindowX
6-37 <Integer> =    WindowY
6-46        WorkWithDocument "Document Name"
6-17 «Logical» =    YES

                                     7-6

                              LoadFlags Appendix

LoadFlags

    It is not necessary to use or understand the LoadFlags, However, they
give you some options on how data is loaded and kept in memory. The LoadFlags
are KEYWORDs that can be added to the end of any load Command. These Commands
are: LoadPicture, LoadBrush, LoadSound, LoadBrushAnim, and LoadDocument.


The LoadFlags are: OVERWRITE CHIP ( DELAYLOAD or ASNEEDED )

    You do not have to specify any of the loadflags or you can use one or
more of them. If you use more than one, do not separate them with commas.


OVERWRITE

    OVERWRITE causes the file to be re-loaded even if it has alredy been
loaded into memory. Normally, a load Command will not re-load the file if it
is currently in memory.


CHIP

    CHIP causes the file to be loaded into the Amiga's CHIP memory.
Loading a file into CHIP memory causes an image to be displayed slightly
faster. However, CHIP memory is a valuable resource. The CHIP loadflag is only
relevant when used with the LoadPicture and LoadBrush Command.


DELAYLOAD or ASNEEDED

    DELAYLOAD or ASNEEDED are used to alter when the file is loaded. By
default, a file is loaded if it is not already in memory. You can specify
either DELAYLOAD or ASNEEDED, but not both.


DELAYLOAD

    DELAYLOAD indicates not to load the until a Show or Play Command is
used. Also, using the DELAYLOAD flag allows you to specify a "Name" other than
the "filename" and still have it automatically loaded. When a Show Command
uses "Name", it will load the "filename" specified in the Load Command.


ASNEEDED

    ASNEEDED does the same thing as DELAYLOAD except it automatically
flushes the loaded file from memory when it is not being used. Normally, the
file remains in memory until it is flushed with a Flush Command or a memory
panic occurs. A memory panic occurs when there is not enough memory to
complete an operation. When this happens, CanDo automatically flushes ALL data
not being used. Even so, running out of memory is a dangerous condition.
ASNEEDED is very useful when there is not a lot of memory and a delay is
acceptable each time the file is used.

    Examples:
        LoadPicture "Images:Background.pic", "Background", DELAYLOAD

        LoadPicture "Images:Background.pic", "Background", CHIP

        LoadPicture "Images:Background.pic", "Background", ASNEEDED CHIP

        LoadPicture "Images:Background.pic", "Background", OVERWRITE

                                     7-7

                              Advanced Features

    CanDo has many features that you may customize to suit your tastes.
These may be changed by editing the ToolTypes in CanDo's icon. Do this by
selecting the CanDo icon and then selecting Info in the Workbench menu. Edit
each ToolType and press Return. An alternate method of setting CanDo's
defaults is to create a text file named CanDo.defaults and save it to your S:
directory. This file should contain the same text as was contained in the
ToolTypes, one ToolType per line. Here are the ToolTypes and an explanaion of
each. If the ToolType is not defined, it will default to the value shown in
brackets ([]).

EDITORTOOLS = "Path" ["EditorTools"]

    The name of the directory where the EditorTool files reside.

XTRAS = "Path" ["XtraTools"]

    The name of the directory where the Xtra Object files reside.

OBJECTS = "Path" ["ObjectTools"]

    The name of the directory where the Object files reside.

HELPFILES = "Path" ["CanDoExtras:HelpFiles"]

    The name of the directory where the Help files reside.

SOUNDS = "Path" ["CanDoExtras:Sounds"]

    This is the default directory in which CanDo looks for your sounds.

IMAGES = "Path" ["CanDoExtras:Images"]

    This is the default directory in which CanDo looks for your images.

BRUSHES = "Path" ["CanDoExtras:Brushes"]

    The default directory in which CanDo looks for your brushes or
    clipped graphics.

BRUSHANIMS = "Path" ["CanDoExtras:BrushAnims"]

    The default directory in which CanDo looks for your DPaintIII
    BrushAnims.

DOCUMENTS = "Path" ["CanDoExtras:Documents"]

    The default directory in which CanDo looks for your text documents.

DECKS = "Path" ["CanDoExtras:Decks"]

    The default directory for saving and loading your decks.

DEFAULTDECK = "PathFile"

    You may set the Deck to be loaded when CanDo is started or when you
    select New from CanDo's Deck Menu.

                                     7-8

SOUNDEFFECTS = On or Off [On]

    This turns all CanDo's sound effects On or Off.

SOUNDVOLUME = 0 to 64 [64]

    This is the volume setting for CanDo's sound effects. It can range
    from 0 (quiet) to 64 (loud).

SCROLLSPEED = 1 to 10 [5]

    This controls how fast CanDo's screen scrolls up and down. It can be
    a value of 1 to 10 where 1 is the fastest.

INHERITWINDOW = On or Off [On]

    When CanDo makes a new card it inherits the current card's window
    (On) or it uses the default window (Off).

COORDINATEDRAG = On or Off [Off]

    When making a box (button, field, etc...) to define an object, this
    flag controls the method of interaction:
        On  = Position, Click, Drag, Release
        Off = Position, Click, Release, Move, Click, Release.

CANDOFONT = "fontname" ["topaz"]

    This defines the font to be used by CanDo. This font must have an
eight point non-proportional render.

AUTOREQUESTERS = On or Off [On]

    This can be used to turn Off (skip showing) intermediate requesters.

CRASHFILE = "PathFile" ["CanDoExtras:Decks/CanDo.CrashDeck"]

    If CanDo crashes, it can store the current Deck to a file. This must
    be a valid path and filename. If the name is a Null ("") then CanDo
    does not store the current Deck.

ICONS = On or Off [On]

    This informs CanDo whether or not to create an icon for Decks that
    are saved.

ICONDEFAULTTOOL = "Default Tool" ["C:CanDoRunner"]

    When CanDo creates an icon for a Deck, this is the default tool for
    the icon. Normally, this should be CanDo.runtime, which is the small
    runtime module that uses the CanDo.Library in your LIBS: directory.
    To make a distributable application be sure to use the CanDoBinder.

    Remember to look on your CanDo and CanDoExtras disk for the ReadMe
files. These files contain last minute information that was not included in
this manual.
    There are many subtl, and not so subtl, methods of easily doing
seemingly complex operations in CanDo's scripting language. Please look
through the example Decks that are included on your CanDoExtras disk. These
Decks have many different scripts that are good examples of scripting. The
best way of learning the ins and outs is to experiment and try new things.

                                     7-9

                                Error Messages

                                Syntax Errors

Unknown Command

    This first word on the line is not a valid Command. You probably
misspelled the Comand or you forgot to type LET for an assignment.

Too many parameters

    The Command line has too many parameters. It's also possible you
provided a parameter for a Command that does not use any.

Not enought parameters

    The Command needs more parameters than you provided.

Unrecognized KEYWORD

    You provided an urecognized word where a KEYWORD was expected. It is
possible you tried to use a variable name in its place.

Conflicting switches specified

    You indicated two or more KEYWORDs that cannot be used together.

Too many IF's

    You have too many IF/ENDIF combinations in your script.

IF without matching ENDIF

    You do not have an ENDIF for every IF Command in your script.

Unexpected ELSE or ENDIF

    You don't have an IF before every ELSE or ENDIF Command.

LOOP/WHILE without matching ENDLOOP/UNTIL

    Your script does not have an ENDLOOP or UNTIL for every LOOP or WHILE
Command in your script.

Unexpected EXITLOOP/ENDLOOP/UNTIL

    You don't have a LOOP or WHILE before every EXITLOOP, ENDLOOP, or
UNTIL Command.

Too many LOOP's

    You have too nany LOOP/WHILE ... ENDLOOP/UNTIL combinations in your
script.

Misplaced operator

    An expression contains a misplaced operator. An operator was found in
a place where a variable or constant was wxpected.

Mismatched parenthesis

    An expression does not have matching parenthesis.

Expression is too complicated

    An expression has too many parenthesis and operations. Simplify the
expression be removing a portion of it and assigning it to a variable. You can
then use the variable in place of this portion.

Invalid expression

    CanDo could not figure out an expression.

                                     7-10

                                Runtime Errors

Named routine not found

    A Do Command attempted to run a routine that does not exist.

Card not found

    A GotoCard Command attempted to go to a card that does not exist.

Named Object not found

    An Object Command referenced an Object that does not exist.

Named Object is wrong type

    the referenced Object can not be used in this context.

Addressed port not found

    The ARexx port specified in an ListenTo Command does not exist.

Named buffer not found

    The "Buffer Name" specified in a Buffer Command does not exist.

Named buffer is wrong type

    The "Buffer Name" can not be used in this context.

Stack overflow

    You have too many nested Do Commands. This probably is because a
Routine is calling itself indefinitely.

Command not allowed in current mode

    This Command cannot be used from within CanDo but it can be used when
your project is running by itself. The System Variable SUPERVISED is true when
your project is running from CanDo.

No Document selected

    You attempted to use a Document Command without first making a
Document.

Name evaluated to a NULL string

    A string evaluated to a NULL ("") when a valid name was required.

Division by ZERO

    An expression contained a division by ZERO (0).

Invalid variable name

    The Command contained an invalid variable name, or an attempt to set
the value of a System Variable or Function. The Command required a variable
name.

                                     7-11

Screen open error

    Not enough chip memory was available in your Amiga to open a screen
the size that is required by your card's window.

Window open error

    Not enought chip memory was available in your Amiga to open your
card's window.

Unknown IFF FORM type

    The IFF file referenced is not of a type CanDo knows how to deal
with. Alternately, it might be a corrupt IFF file.

Brush file has no mask stored with it

    The brush file was saved in a format that does not have a mask, and
one cannot be computed. The mask is used for Image buttons and ShowBrush with
Transparent enabled.

Permature EOF

    A file referenced in your script, or used by one of your Objects, was
not complete.

Not enough memory

    Not enough memory was available in your Amiga to perform the current
operation. CanDo will first try to release any memory is not using at the
moment before resorting to this error.

                                     7-12

                                 File Errors

Object in use

    A file (or device) that your script refeenced is in use bu another
program in your Amiga. Your program must wait until that DOS object is free.

Directory not found

    Your script tried to run a SetCurrentDirectory Command into a
directory that could not be found. Check your script for accuracy.

Object not found

    A file (or device) could not be located using the name as it appeared
in your script. Check the filename for accuracy and correct it.

Wrong file type

    A file that you tried to load (probably as an IFF file) is not of the
currect type.

Disk not validated

    Your script tried to write to a disk or volume that has not been
validated by AmigaDOS.

Disk write-protected

    Your script tried to write to a disk that has been write-protected.

Device not mounted

    A file was referenced on a volume that could not be found.

Disk full

    The disk that your script was writing to has become full. Often, this
can be corrected without interrupting your script by deleting unneeded files
from the full disk.

File delete-protected

    Your script attempted to save a buffer on top of a file already on
the disk that has been protected from deletion.

File write-protected

    Your script opened a WriteFile buffer using a file that is
write-protected.

Not DOS disk

    A disk in your system, referenced by your script, is not a standard
AmigaDOS disk. Disks of this sort cannot be used with CanDo.

                                     7-13

                               T H E   E N D